<HTML><HEAD><TITLE>get_suspension_data(?Susp, +Name, -Value)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Advanced Control and Suspensions</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>get_suspension_data(?Susp, +Name, -Value)</H1>
Access properties of suspended goals.


<DL>
<DT><EM>Susp</EM></DT>
<DD>A suspension or variable.
</DD>
<DT><EM>Name</EM></DT>
<DD>An atom.
</DD>
<DT><EM>Value</EM></DT>
<DD>A variable.
</DD>
</DL>
<H2>Description</H2>
   This built-in is used to access the contents of the abstract suspension
   data type. If applied to an already executed (dead) suspension it fails,
   unless the state information is requested.

<P>
   The accessible properties of a suspension are:

<P>
<PRE>
    Name            Type        Value
    -------------------------------------------------------------
    goal            Term        Suspended goal
    module          Atom        Context module
    qualified_goal  Atom:Term   Lookup module and goal
    priority        Integer     Waking priority
    invoc           Integer     Invocation number (debugging)
    state           Integer     0 (sleeping), 1 (scheduled), 2 (dead)
</PRE>
   Note that a suspension is not a standard logical data structure and can
   only be manipulated in a restricted way.  In particular, a suspension
   cannot be printed (e.g. using writeq/1,2) and then read back, giving a
   term identical to the one that was printed.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>get_suspension_data(?, +, -) is semidet
</UL>
<H3>Fail Conditions</H3>
Fails if Susp is uninstantiated or if the suspension is already dead and Name is not 'state'
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Name is not instantiated.
<DT><EM>(5) type error </EM>
<DD>Susp is not a suspension.
<DT><EM>(5) type error </EM>
<DD>Name is instantiated but not an atom.
<DT><EM>(6) out of range </EM>
<DD>Name is not the name of a suspension property.
</DL>
<H2>Examples</H2>
<PRE>
    [eclipse 4]: make_suspension(writeln(hello), 5, S),
        get_suspension_data(S, priority, P),
        get_suspension_data(S, goal, G),
        get_suspension_data(S, module, M),
        get_suspension_data(S, qualified_goal, QG),
        get_suspension_data(S, invoc, I),
        get_suspension_data(S, state, Z).

    P = 5
    G = writeln(hello)
    M = eclipse
    QG = eclipse : writeln(hello)
    I = 0
    S = 'SUSP-_162-susp'
    Z = 0
    Delayed goals:
        writeln(hello)
    yes.

    [eclipse 2]: suspend(writeln(hello), 3, X-&gt;inst, S),
        get_suspension_data(S, state, Z0),
        call_priority((X=1,true,get_suspension_data(S, state, Z1)), 2),
        get_suspension_data(S, state, Z2).
    hello

    Z0 = 0
    X = 1
    Z1 = 1
    S = 'SUSP-_161-dead'
    Z2 = 2
    yes.



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/suspensions/delayed_goals-1.html">delayed_goals / 1</A>, <A HREF="../../kernel/suspensions/kill_suspension-1.html">kill_suspension / 1</A>, <A HREF="../../kernel/suspensions/make_suspension-3.html">make_suspension / 3</A>, <A HREF="../../kernel/suspensions/get_priority-1.html">get_priority / 1</A>, <A HREF="../../kernel/suspensions/call_priority-2.html">call_priority / 2</A>, <A HREF="../../kernel/suspensions/suspend-3.html">suspend / 3</A>, <A HREF="../../kernel/suspensions/suspensions-1.html">suspensions / 1</A>, <A HREF="../../kernel/suspensions/current_suspension-1.html">current_suspension / 1</A>, <A HREF="../../kernel/suspensions/set_suspension_data-3.html">set_suspension_data / 3</A>
</BODY></HTML>
